package com.polymathcoder.dpastry.api.pastry;

import com.polymathcoder.dpastry.api.environment.RandomSource;

import java.util.Random;
import java.util.SortedMap;

/**
 * Created by IntelliJ IDEA.
 * User: Drew
 * Date: Jul 5, 2010
 * Time: 9:11:26 AM
 * To change this template use File | Settings | File Templates.
 */
public interface IdFactory {
    /**
     * Builds a protocol-specific Id given the source data.
     *
     * @param material The material to use
     * @return The built Id.
     */
    public Id buildId(byte[] material);

    /**
     * Builds a protocol-specific Id given the source data.
     *
     * @param material The material to use
     * @return The built Id.
     */
    public Id buildId(int[] material);

    /**
     * Builds a protocol-specific Id by using the hash of the given string as source data.
     *
     * @param string The string to use as source data
     * @return The built Id.
     */
    public Id buildId(String string);

    /**
     * Builds a random protocol-specific Id.
     *
     * @param rng A random number generator
     * @return The built Id.
     */
    public Id buildRandomId(Random rng);

    /**
     * Builds a random Id using the "Environment" Random Source
     * //@TODO: Environment Random Source?
     *
     * @param rng
     * @return
     */
    public Id buildRandomId(RandomSource rng);

    /**
     * Builds an IdRange based on a prefix.  Any id which has this prefix should
     * be inside this IdRange, and any id which does not share this prefix should
     * be outside it.
     *
     * @param string The toString() representation of an Id
     * @return The built Id.
     */
    public IdRange buildIdRangeFromPrefix(String string);

    /**
     * Returns the length a Id.toString should be.
     *
     * @return The correct length;
     */
    public int getIdToStringLength();

    /**
     * Builds a protocol-specific Id.Distance given the source data.
     *
     * @param material The material to use
     * @return The built Id.Distance.
     */
    public Id.Distance buildIdDistance(byte[] material);

    /**
     * Creates an IdRange given the CW and CCW ids.
     *
     * @param cw  The clockwise Id
     * @param ccw The counterclockwise Id
     * @return An IdRange with the appropriate delimiters.
     */
    public IdRange buildIdRange(Id cw, Id ccw);

    /**
     * Creates an empty IdSet.
     *
     * @return an empty IdSet
     */
    public IdSet buildIdSet();

    /**
     * Creates an empty IdSet.
     *
     * @return an empty IdSet
     * @Param map The map which to take the keys from to create the IdSet's elements
     */
    public IdSet buildIdSet(SortedMap map);

    /**
     * Creates an empty NodeHandleSet.
     *
     * @return an empty NodeHandleSet
     */
    public NodeHandleSet buildNodeHandleSet();
}
